Improving the GraphQL, JSON and RDF Representations of buildingSmart Data Dictionary
PlantUML is used with soml2puml convertor tool
ReferenceDocument, Country, Unit, Language are disconnected from the rest of the schemaRootAt the high level of detail:
Property and ClassificationProperty are very similar, but there’s no inheritance/relation between themPropertyValue and ClassificationPropertyValue are exactly the same, so can be reduced to one entityMixture of singular/plural in property names
property/properties, relations, synonyms, countriesOfUse, relatedIfcPropertyNames, etc.
RootClassification hierarchy can be navigated both up and down (parentClassification, childClassification)Relation entity to get data about the related entity:
Classification.relation -> ClassificationRelation.related -> ClassificationProperty.relation -> PropertyRelation.related -> PropertyPropertyValue is used by both Property and ClassificationPropertyFebruary 2023: IfcCableSegment has id: https://search.bsdd.buildingsmart.org/Classification/Index/58453
May 2023: IfcCableSegment has another id: https://search.bsdd.buildingsmart.org/Classification/Index/70992
IfcCableSegment has also unique URI:
https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcCableSegmentCABLESEGMENT
Non-unique identification violates FAIR Findability principle
F1: (Meta)data are assigned a globally unique and persistent identifier
We have compared three representations returned by the bSDD server:
https://test.bsdd.buildingsmart.org/graphiql/,curl https://identifier.buildingsmart.org/uri/buildingsmart/ <domain>/class|prop/<name> andcurl -Haccept:text/turtle \\ https://identifier.buildingsmart.org/uri/buildingsmart/ <domain>/class|prop/<name>We selected entities of each class that have the maximum number of filled fields, and compared the results returned by each API.
Recommendations on ontology URI design, including versioning and opaque URIs to maintain evolution and multilingualism inherent to bSDD, are described in Garijo & Poveda-Villalon, 2020.
Almost all bSDD domain URLs now have the same structure: https://identifier.buildingsmart.org/uri/<org>/<domain>-<version>
URIs can be more ``hackable’’, allowing users to navigate the hierarchy by pruning the URI: https://identifier.buildingsmart.org/uri/<org>/<domain>/<version>
<org> is repeated in the <domain> part<org> name doesn’t quite mesh with the domain name, perhaps due to the way bSDD allocates <org> identifiers to bSDD contributors
bim-de/DINSPEC91400: the publisher of this spec is DIN (the German standards organization), not the bim-de initiativedigibase/volkerwesselsbv: bimregister.nl news from 2018 suggest that digibase is a new company/initaitive within Volker Wesseldigibase/nen2699: the publisher of this spec is NEN (the Netherlands standards organization), not the digibase company/initiativedigibase/digibasebouwlagen: perhaps the org name digibase should not be repeated as the prefix of the domain bouwlagen (building layers)https://identifier.buildingsmart.org/uri/acca/ACCAtest-0.1
can become
https://identifier.buildingsmart.org/uri/acca/ACCAtest/0.1
A new entity DomainVersion can provide linking all versions of a domain to its master Domain entity.
ID and use a mandatory field id
id, whereas bSDD uses namespaceUrinamespaceUri field, or it is not fully populatedThe key field classificationType specifies the kind of classification.
| c | classificationType | overlaps with entity |
|---|---|---|
| 29 | “DOMAIN” | Domain |
| 18 | “REFERENCE_DOCUMENT” | ReferenceDocument |
Examples of unusual classifications:
https://identifier.buildingsmart.org/uri/ATALANE/REX-OBJ-1.0/class/589b06ad-f802-468b-939c-e60436601a7a is a “REFERENCE_DOCUMENT” with name “décret 2011-321 (23/03/2011)”.
Why is it not a ReferenceDocument entity?
All significant classes should have ID, which in the case of RDF data is the node URL.
However, many bSDD classes don’t have such a field:
Domain, Property, Classification do have namespaceUriCountry, Language, Unit don’t have an ID but have a field (code, isocode) that can be used to make an ID, when prepended with an appropriate prefix.Property and ClassificationProperty are two different classes, but the latter does not have a distinct URL in GraphQL and JSON.
The same URL is overloaded to identify entities of both classes.
ClassificationProperty are thus “second class” entities and are not returned separately by the JSON or RDF entity API, but only as part of the respective Classification
curl https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcCableSegmentCABLESEGMENT/ACResistance
{"":["Classification with namespace URI
'https://identifier.buildingsmart.org/uri/buildingsmart/ifc-4.3/class/IfcCableSegmentCABLESEGMENT/ACResistance'
not found"]}
The key attribute propertyValueKind has values COMPLEX and COMPLEX_LIST used in combination with connectedProperties. These key values are defined for Property and ClassificationProperty
connectedPropertyCodes is defined only for PropertyconnectedProperty is used only on 7 Properties (and not ClassificationProperties)Instead of using connectedPropertyCodes to describe complex properties, some providers have used classifications with the type COMPOSED_PROPERTY.
12385 Properties are declared as isDynamic (135250 are not).
However, the field dynamicParameterPropertyCode (used to compute the dynamic property) is always empty, so how can one know which “sub-properties” to use?
Additionally, dynamicParameterPropertyCodes is String, but should be [Property], i.e. an array of Properties .
bSDD includes numerous string attributes (codes or URLs) that should be converted to relations (object fields) to improve the connectedness of the bSDD GraphQL graph
| is a classification field (String) | should be |
|---|---|
physicalQuantity |
(New) PhysicalQuantity |
propertySet |
(New) PropertySet |
subdivisionsOfUse |
(New) [CountrySubdivision |
version |
(New) DomainVersion |
replaced/(-ing)ObjectCodes |
some kind of objects. Currently they are empty |
Property and ClassificationProperty: differ in only 5 fields:
connectedPropertyCodes (String) and relations (PropertyRelation) belong uniquely to PropertyisRequired (Boolean), isWritable (Boolean), predefinedValue (String), propertySet (String) and symbol (String) below uniquely to ClassificationProperty.Since there are no rules on which fields of Property to reuse in ClassificationProperty, the latter type copies most of the fields from the former.
PropertyValuesPropertyValue and ClassificationPropertyValue are structured values with rich fields: code, value, namespaceUri, description, sortNumber, allowing to:
However, most structured values we’ve seen have only code, value.
This has multiple problems:
description is not filled out)namespaceUri, precluding unique identification.predefinedValueallowedValues (and its deprecated variant possibleValues) store structured values (ClassificationPropertyValue)
However, their “sibling” property predefinedValue holds just a String, which means that even in the future, predefinedValue cannot be an enumeration value identified globally with a URL.
bSDD is advertised as a multilingual dictionary. In the GraphQL API, one can specify a desired language when fetching classifications and properties: However, most domains are present in one language only (unilingual).
We encountered various data quality issues:
We implemented a lot (but not all) of the improvements suggested above by using the following process:
Here are further ideas for improvement:
Property/ClassificationProperty descriptions and creation of corresponding PropertyValue lists
Funding: ACCORD project, Horizon Europe, grant #101056973
Data: buildingSMART Data Dictionary (bSI credits: Leon van Berlo, Artur Tomczak, Erik Baars)
Powered by:
11th Linked Data in Architecture and Construction Workshop, 15–16 June 2023, Matera, Italy